home *** CD-ROM | disk | FTP | other *** search
/ Aminet 24 / Aminet 24 (1998)(GTI - Schatztruhe)[!][Apr 1998].iso / Aminet / dev / c / cpost_1_4.lha / cpost.doc < prev    next >
Text File  |  1995-05-09  |  18KB  |  473 lines
  1.  
  2.  
  3.             cPost - C language file formatter for PostScript
  4.  
  5.                            by Patrick Mueller
  6.  
  7.                           pmuellr@vnet.ibm.com
  8.  
  9.  
  10. ----------------------------------------------------
  11. What is cPost?
  12. ----------------------------------------------------
  13.  
  14. cPost is a program which will take a number of c and h files as input
  15. and create a PostScript file.  The PostScript file will contain the
  16. contents of the input files that have been marked up so that various
  17. parts are highlighted.
  18.  
  19. ----------------------------------------------------
  20. cPost invocation and options
  21. ----------------------------------------------------
  22.  
  23. When cPost is invoked, it examines the command line for file names and
  24. options.  The file names may contain wildcards.  Running cPost with no
  25. file names or with a ? as the first parameter will write some brief help
  26. to standard error.
  27.  
  28. Options are blank delimited 'words' which begin with a '-'.  The case of
  29. the character following the - is not significant.  Options may be placed
  30. before, after or in between file names.  If the same option is specified
  31. more than once on the command line, only the last option is used.
  32. Options may also be specified in the CPOST environment variable.
  33. Command line options override environment variable options.
  34.  
  35. A typical invocation of cPost might be
  36.  
  37.    cpost *.c *.h > project.ps
  38.  
  39. This invocation will include all c and h files, use any options
  40. set in the CPOST environment variable, and write the output to the
  41. file 'project.ps'.
  42.  
  43. Note that the options used in the environment variable are used as-is,
  44. which means that quote processing which is normally done on the OS/2
  45. commandline parameters is not done on environment variable values.
  46. Thus, it is not possible to use an option which has a value which
  47. includes spaces.
  48.  
  49. You may also use a list file to determine the files to process.
  50. The list file is just a plain text file that contains the names of
  51. other files in it.  Prepend the list file name with a '@' when you
  52. use it on the command line.  The list file can contains any number
  53. of file names.  They can be entered on one line apiece, or multiple
  54. names can be on one line as long as they are separated with white
  55. space.  Blank lines, and lines that begin with a '#' character
  56. are ignored.  If a '@-' is given on the command line, file names
  57. to process will be read from stdin.
  58.  
  59. Valid options are:
  60.  
  61.     -b[+|-]
  62.     enable/disable bracketing level
  63.  
  64.        Use -b+ to have all levels of braces within file bracketed.  Use
  65.        -b- to cause no bracketing.
  66.  
  67.     -cext1,ext2,...
  68.     treat files with extension ext1 and ext2 as C files
  69.  
  70.        For example, -cc,y,sqc will cause files with 'extensions' c, y,
  71.        and sqc (case insensitive) to be considered c files.  This
  72.        information is used to determine sorting order.  Note that the
  73.        'extension' is considered the text after the first '.' in the
  74.        name, up to the last character, or next '.' in the name.
  75.  
  76.     -d[+|-]
  77.     enable/disable duplex
  78.  
  79.        Duplex processing causes two things to happen:  the header1 proc
  80.        is used for odd number pages, and the header2 proc is used for
  81.        even number pages; and a blank page will be printed for files
  82.        that end on an odd numbered page.  If duplexing is not on, the
  83.        header1 proc is used for both even and odd pages, and extra blank
  84.        pages will not be printed.  The header1 and header2 procs may be
  85.        customized with the -i option.
  86.  
  87.     -hext1,ext2,...
  88.     treat files with extension ext1 and ext2 as H files
  89.  
  90.        For example, -hh,rh,sqh will cause files with 'extensions' h, rh,
  91.        and sqh (case insensitive) to be considered h files.  This
  92.        information is used to determine whether function definition and
  93.        usage are valid within the file, and to determine sorting order.
  94.        Note that the 'extension' is considered the text after the
  95.        first '.' in the name, up to the last character, or next '.' in
  96.        the name.
  97.  
  98.     -ifile1;file2;...
  99.     imbed PostScript files into the output file
  100.  
  101.        This option is used to redefine fonts, margins and headers for
  102.        your document.  Multiple files can be imbedded - they will be
  103.        imbedded in the order specified.  See Customization below.
  104.  
  105.     -kkey1,key2,...
  106.     treat key1, key2, etc as reserved words
  107.  
  108.        In addition to the ANSI reserved words, the following are
  109.        considered reserved (SAA extensions):  _Packed, _System,
  110.        _Optlink, _Far16, _Cdecl, _Pascal.  If one of the keys specified
  111.        is 'c++', the following tokens will be considered reserved words:
  112.        catch, class, delete, friend, inline, new, operator, private,
  113.        protected, public, template, this, throw, try, virtual.  To make
  114.        additional words reserved, use the -k option.  For instance,
  115.        -kNULL,FILE adds NULL and FILE as reserved words.  This option is
  116.        used merely to control the highlighting of the tokens.
  117.  
  118.        You may also use a file that contains the keywords.  To do this,
  119.        prepend a '@' to the filename, and use that as a key on the -k
  120.        option.  The contents of the file should be in the same format
  121.        as list files, described above, except keywords are enclosed in
  122.        the file, and not filenames.
  123.  
  124.     -n#
  125.     separate line numbers from lines with # spaces.
  126.  
  127.        When 0 is specified, no line numbers are generated.
  128.  
  129.     -ofileName
  130.     output written to the file named fileName.
  131.  
  132.        Without this option, output is written to stdout.
  133.  
  134.     -p[+|-]
  135.     enable/disable best-fit page break at functions
  136.  
  137.        When this option is enabled, functions that can fit on a page by
  138.        themselves will be printed on a single page.  Basically this means
  139.        that page ejects occur between functions.  But if multiple
  140.        functions do fit on a page, they will be printed on a page
  141.        together.
  142.  
  143.     -rfile1;file2;...
  144.     replace default PostScript procedures with those in another file
  145.  
  146.        This option is used to replace the PostScript procedures
  147.        generated by cPost with your own.  This is for power-users
  148.        who think they can produce nicer looking output than I can!
  149.        See customization below.
  150.  
  151.     -snt or -stn
  152.     sort files by name/type or type/name
  153.  
  154.        When sorting by type, the files are first sorted by whether they
  155.        are c, h, or neither (see -c and -h options), and then by the
  156.        actual extension.  All sorting is done in a case insensitive
  157.        manner.
  158.  
  159.     -t#
  160.     expand tabs to # columns
  161.  
  162.        The default is 4, which causes the characters immediately
  163.        following tab characters to be placed in columns 5, 9, 13, ...
  164.  
  165.     -xx,y
  166.     coordinates to with translate for page
  167.  
  168.        This option is provided to help bridge the difference between
  169.        PostScript printers.  Because the printable area on printers is
  170.        different, you might create a set of margin and header
  171.        definitions that print fine on one printer, but are clipped on
  172.        another printer.  This option inserts a translate operation into
  173.        the PostScript file before a page is written to, to offset the
  174.        printing by a certain amount.  For example, -x0,18 would be used
  175.        to move the printout on the page up 1/4 inch.  The units must be
  176.        given in points (72 points/inch).
  177.  
  178.     -ypath
  179.     path to use for temporary files
  180.  
  181.        A copy of each input file read is created during the cPost run.
  182.        By default, these copies are created in your current directory.
  183.        This option allows you to specify a different location for the
  184.        temporary files.
  185.  
  186.     -?
  187.     display online help
  188.  
  189.  
  190. The default options are
  191.  
  192.     -b+ -d- -cc -hh -n2 -p+ -stn -t4 -x0,0
  193.  
  194. ----------------------------------------------------
  195. Customizing cPost output
  196. ----------------------------------------------------
  197.  
  198. Customization of the cPost output is done by including additional
  199. PostScript code in the output file, and optionally not adding some of
  200. the PostScript code normally written by cPost.  The code you add must be
  201. valid PostScript code - it is not checked or processed by cPost at all.
  202. The output of cPost can be used as a starting point for creating new
  203. code.  For an intro